home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / stk-3.0 / stk-3 / blt-for-STk-3.0 / blt-1.9 / man / table.man < prev    next >
Encoding:
Text File  |  1995-12-18  |  16.9 KB  |  409 lines
  1. '\"
  2. '\" Copyright 1991-1994 by AT&T Bell Laboratories.
  3. '\"
  4. '\" Permission to use, copy, modify, and distribute this software
  5. '\" and its documentation for any purpose and without fee is hereby
  6. '\" granted, provided that the above copyright notice appear in all
  7. '\" copies and that both that the copyright notice and warranty
  8. '\" disclaimer appear in supporting documentation, and that the
  9. '\" names of AT&T Bell Laboratories any of their entities not be used
  10. '\" in advertising or publicity pertaining to distribution of the
  11. '\" software without specific, written prior permission.
  12. '\"
  13. '\" AT&T disclaims all warranties with regard to this software, including
  14. '\" all implied warranties of merchantability and fitness.  In no event
  15. '\" shall AT&T be liable for any special, indirect or consequential
  16. '\" damages or any damages whatsoever resulting from loss of use, data
  17. '\" or profits, whether in an action of contract, negligence or other
  18. '\" tortuous action, arising out of or in connection with the use or
  19. '\" performance of this software.
  20. '\"
  21. '\" Table geometry manager created by George Howlett.
  22. '\"
  23. .so man.macros
  24. .HS blt_table cmds
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. blt_table \- Geometry manager that arranges windows in a table
  29. .SH SYNOPSIS
  30. .sp
  31. \fBblt_table \fImaster\fR ?\fIslave index options\fR?...
  32. .sp
  33. \fBblt_table arrange \fImaster\fR
  34. .sp
  35. \fBblt_table column \fImaster option\fR ?\fIargs\fR...?
  36. .sp
  37. \fBblt_table configure \fIslave\fR ?\fIslave\fR...? ?\fIoptions\fR...?
  38. .sp
  39. \fBblt_table row \fImaster option\fR ?\fIargs\fR...?
  40. .sp
  41. \fBblt_table forget \fIslave\fR ?\fIslave\fR...?
  42. .sp
  43. \fBblt_table info \fIslave\fR
  44. .sp
  45. \fBblt_table slaves \fImaster\fR ?\fIpattern\fR?
  46. .sp
  47. \fBblt_table masters\fR ?\fIpattern\fR?
  48. .BE
  49. .SH DESCRIPTION
  50. .PP
  51. The \fBblt_table\fR command is a geometry manager for Tk. It arranges 
  52. windows tabularly in
  53. a window called the \fImaster\fR.  The table consists of individual
  54. rows and columns whose spacing define its layout. Windows, called 
  55. \fIslaves\fR, are positioned in the table by specifying the row and column.
  56. Only one slave can be specified at a single position in the table.  But slaves 
  57. may span multiple rows and columns.
  58. .PP
  59. By default, \fBblt_table\fR tries to arrange all its slaves in the minimum 
  60. space required. It determines this by querying each slave window for
  61. its requested size.  The maximum requested height all slaves spanning a 
  62. particular row is the row's normal size.  Similarly, the maximum 
  63. requested width of all slaves spanning a particular column is the column's 
  64. normal size.  This, in turn, specifies the table's size, which 
  65. is the sum of the normal sizes of the rows and columns.
  66. The number of rows and columns a table contains
  67. is determined by the indices specified.  
  68. There is no mechanism to delete a row or column.
  69. .SH TABLE INDICES
  70. An \fIindex\fR references a row,column position in the table.
  71. It must be in the form "\fIrow\fR,\fIcolumn\fR" where \fIrow\fR and 
  72. \fIcolumn\fR are the respective row and column
  73. numbers, starting from zero  (0,0 is the upper leftmost  position). 
  74. \fIRow\fR and \fIcolumn\fR may also be numeric expressions which are 
  75. recursively evaluated.  
  76. .SH SIZE CONSTRAINTS
  77. You can limit the amount of space requested by a slave window.
  78. By specifying both a minimum and maximum limit in which the window's 
  79. requested size must fall, you can bound a window's size.  This affects
  80. the calculation of the normal size of all rows and columns which
  81. it spans. In a similar fashion, you can directly control the 
  82. normal size of any row or column. 
  83. .PP
  84. This provides two features.
  85. Slave windows must be contained within the rows and columns they are 
  86. defined to span.  By limiting the size of a row or column, you control 
  87. the size of all windows in spanning it. This overrides whatever
  88. size the slave has requested.  Secondly, there's no requirement 
  89. that a row or column contain any slaves. This means you can create 
  90. horizontal or vertical spacing by simply setting the row or column limits.
  91. .SH RESIZING
  92. \fBBlt_table\fR tries to fit itself exactly in the master window.  It first
  93. tries to change the size of the master to the table's normal size.
  94. If this fails, it then tries to expand or shrink itself to the size of 
  95. the master.
  96. If normal size of the table is smaller than the master window, the 
  97. extra space is evenly divided among the rows or columns. If it's larger, 
  98. then the row and columns are shrunk to fit in the master window.  In both 
  99. cases, the rows and column sizes are changed with respect to their constraints.
  100. .PP
  101. You can also specify how an individual row or column is to be resized. 
  102. For example, a column may be set to one of four modes:
  103. .RS
  104. .IP \fBnone\fR
  105. Don't resize the column.
  106. .IP \fBexpand\fR
  107. Allow the column to only grow greater than its normal width.
  108. .IP \fBshrink\fR
  109. Allow the column to only shrink less than its normal width.
  110. .IP \fBboth\fR
  111. Resize the column in either direction.
  112. .RE
  113. .SH CREATING A TABLE
  114. Tables are created by invoking the \fBblt_table\fR command.
  115. .DS
  116.     \fBblt_table\fR \fImaster\fR
  117. .DE
  118. \fIMaster\fR is the pathname of a window which must already exist.
  119. \fBBlt_table\fR will arrange its slave windows inside of \fImaster\fR.
  120. Slave windows are added by designating the slave window's pathname and 
  121. table position.
  122. .DS
  123.     \fBblt_table\fR \fImaster slave index\fR
  124. .DE
  125. .SH TABLE COMMANDS
  126. The following commands are available for the \fBblt_table\fR:
  127. .TP
  128. \fBblt_table arrange \fImaster\fR
  129. Forces the recalculation of the table layout, which is normally deferred
  130. to the next idle time.
  131. .TP
  132. \fBblt_table \fImaster\fR ?\fIslave index options\fR?...
  133. Adds the window \fIslave\fR to the table associated with \fImaster\fR.
  134. If a table doesn't exist for \fImaster\fR, one is created.
  135. \fIMaster\fR is the pathname of the window in which the slave windows
  136. will be arranged. \fISlave\fR is the pathname of the window to be arranged
  137. inside of \fImaster\fR at the position designated by \fIindex\fR.
  138. This command returns the empty string.  
  139. \fIOption\fR may have any of the values accepted by the 
  140. \fBblt_table configure\fR command.
  141. .TP
  142. \fBblt_table column \fImaster \fBconfigure \fIcolumnIndex\fR ?\fIoptions...\fR?
  143. Queries or modifies the configuration options of the columns specified.
  144. \fIColumnIndex\fR may be in one of two forms; \fBall\fR 
  145. (indicating all columns) or a list of the column indices to be configured.  
  146. \fIOptions\fR may have any of the following values:
  147. .RS
  148. .TP
  149. \fB\-padx \fIpixels\fR
  150. Specifies an extra padding to the normal width of the column.
  151. \fIPixels\fR can be any value accepted by \fBTk_GetPixels\fR.
  152. The default padding is \fB0\fR.
  153. .TP
  154. \fB\-resize \fImode\fR
  155. Indicates that the column can expand or shrink from its normal width 
  156. when the table is resized.
  157. \fIMode\fR must be one of the following:
  158. \fBnone\fR, \fBexpand\fR, \fBshrink\fR, or \fBboth\fR.  If \fImode\fR is 
  159. \fBexpand\fR the width of the column is expanded if there is extra space
  160. in the master window. If \fIstyle\fR is \fBshrink\fR its width may be
  161. reduced beyond its normal width if there is not enough space in the master.
  162. The default is \fBnone\fR.
  163. .TP
  164. \fB\-width \fIwidth\fR
  165. Specifies the limits within which the width of the column may expand or 
  166. shrink.  
  167. \fIWidth\fR is a list of bounding values.  See the section 
  168. .SB BOUNDING LIST FORMAT
  169. for a description of this list.
  170. By default there are no constraints.
  171. .RE
  172. .TP
  173. \fBblt_table column \fImaster\fB dimension\fR
  174. Returns the number of columns in the table.
  175. .TP
  176. \fBblt_table column \fImaster \fBinfo\fI columnIndex\fR 
  177. Returns a list of the configuration options for the columns specified.
  178. \fIColumnIndex\fR may be in one of two forms; \fBall\fR 
  179. (indicating all columns) or a list of column indices.
  180. The column indices may themselves be numeric expressions.
  181. .TP
  182. \fBblt_table column \fImaster\fB location\fI position\fR
  183. returns the column number containing pixel \fIposition\fR,
  184. where pixel 0 is the left edge of the first column.
  185. .TP
  186. \fBblt_table column \fImaster\fB sizes\fI columnIndex\fR
  187. Returns the sizes of the given columns in the table.
  188. \fIColumnIndex\fR may be in one of two forms; \fBall\fR 
  189. (indicating all columns) or a list of column indices. 
  190. The column indices may themselves be numeric expressions.
  191. .TP
  192. \fBblt_table configure\fR \fIslave\fR ?\fIslave\fR...? ?\fIoptions\fR...? 
  193. Queries or modifies the configuration options of a slave in a table.  
  194. If no \fIoption\fR is specified, returns a list describing all of the
  195. available options for \fIslave\fR (see \fBTk_ConfigureInfo\fR for
  196. information on the format of this list).  \fISlave\fR must be
  197. the pathname of a window already managed by the \fBblt_table\fR.
  198. If \fIoption\fR is specified with no \fIvalue\fR, then the command 
  199. returns a list describing the
  200. one named option (this list will be identical to the corresponding
  201. sublist of the value returned if no \fIoption\fR is specified).  
  202. If one or more \fIoption\-value\fR pairs are specified, then the command
  203. modifies the given option(s) to have the given value(s); in
  204. this case the command returns the empty string.  
  205. One of more slave windows can be modified (with the 
  206. same options) at the same time.
  207. The following configuration 
  208. options are valid:
  209. .RS
  210. .TP
  211. \fB\-anchor \fIanchorPos\fR
  212. Specifies how the slave window will be arranged if there is extra space 
  213. in the span surrounding the window. \fIAnchorpos\fR may have any of the 
  214. forms accepted by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR is 
  215. \fBcenter\fR then the window is centered in the rows and columns it spans; 
  216. if \fIanchorPos\fR is \fBw\fR then the window will be drawn such it touches
  217. the leftmost edge of the span. This option defaults to \fBcenter\fR.
  218. .TP
  219. \fB\-columnspan \fInumber\fR
  220. Specifies the number of columns spanned by the slave. The default span
  221. is \fB1\fR.
  222. .TP
  223. \fB\-fill \fIstyle\fR
  224. Indicates if the slave should be expanded to occupy any extra space 
  225. in the span.  \fIStyle\fR must be one of the following:
  226. \fBnone\fR, \fBx\fR, \fBy\fR, \fBboth\fR.  If \fIstyle\fR is \fBx\fR,
  227. the width slave window is expanded.  If \fIstyle\fR is \fBy\fR, the
  228. height is expanded. The default is \fBnone\fR.
  229. .TP
  230. \fB\-ipadx \fIpixels\fR
  231. Specifies an extra padding in addition to the width requested by the 
  232. slave window. \fIPixels\fR can be any value accepted by \fBTk_GetPixels\fR.
  233. The default is \fB0\fR.
  234. .TP
  235. \fB\-ipady \fIpixels\fR
  236. Specifies an extra padding in addition to the height requested by the slave window. \fIPixels\fR can be any value accepted by \fBTk_GetPixels\fR.
  237. The default is \fB0\fR.
  238. .TP 
  239. \fB\-padx \fIpixels\fR
  240. Specifies an extra padding to the width of the span occupying the slave window. 
  241. \fIPixels\fR can be any value accepted by \fBTk_GetPixels\fR.
  242. The default is \fB0\fR.
  243. .TP
  244. \fB\-pady \fIpixels\fR
  245. Specifies an extra padding to the height of the span occupying the slave window.
  246. \fIPixels\fR can be any value accepted by \fBTk_GetPixels\fR.
  247. The default is \fB0\fR.
  248. .TP
  249. \fB\-reqheight \fIheight\fR
  250. Specifies limits for the requested height of the slave window. These limits 
  251. also constrain the amount of internal padding given to the slave. 
  252. \fIHeight\fR is a list of bounding values.  See the section 
  253. .SB BOUNDING LIST FORMAT
  254. for a description of this list.
  255. By default there are no constraints.
  256. .TP
  257. \fB\-reqwidth \fIwidth\fR
  258. Specifies the limits of the width which a slave may request. These limits 
  259. also affect the amount of internal padding given to the slave.
  260. \fIWidth\fR is a list of bounding values.  See the section 
  261. .SB BOUNDING LIST FORMAT
  262. for a description of this list.
  263. By default there are no constraints.
  264. .TP
  265. \fB\-rowspan \fInumber\fR
  266. Specifies the number of rows spanned by the slave window. The default span
  267. is \fB1\fR.
  268. .RE
  269. .TP
  270. \fBblt_table forget \fIslave\fR 
  271. Requests that \fIslave\fR no longer have its geometry managed.
  272. \fISlave\fR is the pathname of the window currently 
  273. managed by some table. The window will be unmapped so that it no longer 
  274. appears on the screen.  If \fIslave\fR is not currently managed by any table, 
  275. an error message is returned, otherwise the empty string.
  276. .TP
  277. \fBblt_table info \fIslave\fR 
  278. Returns a list of the current non-default configuration options of for 
  279. \fIslave\fR.  \fISlave\fR is the pathname of the window currently managed 
  280. by some table.  The list is exactly in the form that might be specified to
  281. \fBblt_table configure\fR command.
  282. If \fIslave\fR is not currently managed by any table, an error
  283. message is returned.
  284. .TP
  285. \fBblt_table masters \fR?\fIpattern\fR?
  286. Returns a list of pathnames for all master windows matching \fIpattern\fR.  
  287. If the \fIpattern\fR argument is not present, then the names of all the master 
  288. windows are returned.
  289. .TP
  290. \fBblt_table row \fImaster\fB configure\fI row\fR ?\fIoptions...\fR?
  291. Queries or modifies the configuration options of the row specified 
  292. by \fIrow\fR. \fIRow\fR may be in one of two forms; \fBall\fR 
  293. (indicating all rows) or a list of the row indices to be configured.  
  294. \fIOption\fR may have any of the values accepted by the following:
  295. .RS
  296. .TP
  297. \fB\-height \fIheight\fR
  298. Specifies the limits of the height which the row may expand or shrink to. 
  299. \fIHeight\fR is a list of bounding values.  See the section 
  300. .SB BOUNDING LIST FORMAT
  301. for a description of this list.
  302. By default there are no constraints.
  303. .TP
  304. \fB\-pady \fIpixels\fR
  305. Specifies an extra padding to the normal height of the row.
  306. \fIPixels\fR can be any value accepted by \fBTk_GetPixels\fR.
  307. The default padding is \fB0\fR.
  308. .TP
  309. \fB\-resize \fImode\fR
  310. Indicates that the row can expand or shrink from its normal height 
  311. when the table is resized.
  312. \fIMode\fR must be one of the following:
  313. \fBnone\fR, \fBexpand\fR, \fBshrink\fR, or \fBboth\fR.  If \fImode\fR is 
  314. \fBexpand\fR the height of the row is expanded if there is extra space
  315. in the master window. If \fIstyle\fR is \fBshrink\fR its height may be
  316. reduced beyond its normal height if there is not enough space in the master.
  317. The default is \fBnone\fR.
  318. .RE
  319. .TP
  320. \fBblt_table row \fImaster\fB dimension\fR
  321. Returns the number of rows in the table.
  322. .TP
  323. \fBblt_table row \fImaster\fB info\fI row\fR ?\fIoptions...\fR?
  324. Returns a list of the configuration options for the rows specified.
  325. \fIRowIndex\fR may be in one of two forms; \fBall\fR 
  326. (indicating all rows) or a list of row indices.
  327. The row indices may themselves be numeric expressions.
  328. .TP
  329. \fBblt_table row \fImaster\fB location\fI position\fR
  330. returns the row number containing pixel \fIposition\fR,
  331. where pixel 0 is the top edge of the first row.
  332. .TP
  333. \fBblt_table row \fImaster\fB sizes\fI rowIndex\fR
  334. Returns the sizes of the given rows in the table.
  335. \fIRowIndex\fR may be in one of two forms; \fBall\fR 
  336. (indicating all rows) or a list of the row indices.
  337. .TP
  338. \fBblt_table slaves \fImaster\fR ?\fIoptions\fR?
  339. Returns a list of pathnames for slave windows managed by 
  340. \fImaster\fR that match the conditions set forth in \fIoptions\fR.
  341. If no \fIoption\fR argument is
  342. present, then the names of all the slave windows are returned.
  343. \fIMaster\fR is the pathname of a master window.
  344. If \fImaster\fR is not the master window of any table, an error message 
  345. is returned.
  346. The options consist of one or more of:
  347. .RS
  348. .TP
  349. \fB-column\fI n\fR?
  350. Slaves that do not occupy column \fIn\fP are excluded.
  351. .TP
  352. \fB-exclude\fI pattern\fR?
  353. Slaves that match the glob style pattern \fIpattern\fP are excluded.
  354. .TP
  355. \fB-match\fI pattern\fR?
  356. Slaves that do not match the glob style pattern \fIpattern\fP are excluded.
  357. .TP
  358. \fB-row\fI n\fR?
  359. Slaves that do not occupy row \fIn\fP are excluded.
  360. .RE
  361. .SH BOUNDING LIST FORMAT
  362. Constraints for various options 
  363. (\fB-reqheight\fR, \fB-reqwidth\fR, \fB-height\fR, and \fB-width\fR) are 
  364. specified by supplying a bounding list of values.
  365. Each value must be in a form accepted by \fBTk_GetPixels\fR.
  366. The interpretation of this list is based upon the number of values it
  367. contains:
  368. .RS
  369. .IP "{\fI\fR}"
  370. Empty list. No bounding is performed.
  371. .IP "{\fI x \fR}"
  372. Set the size of the window or partition at \fIx\fR. The size of the partition 
  373. or window cannot grow or shrink.
  374. .IP "{\fI min max \fR}"
  375. Bound the size of the window or partition between \fImin\fR
  376. and \fImax\fR.
  377. .IP "{\fI min max nom\fR}"
  378. Bound the size of the window or partition between \fImin\fR
  379. and \fImax\fR.  In addition, set the normal size to \fInom\fR.
  380. .RE
  381. The maximum bound \fImax\fR can also be specified as \fCInf\fR
  382. to indicate a unlimited maximum bound.  This can be useful when you 
  383. wish only to set the minimum or nominal size of a window or partition.
  384. .SH EXAMPLE
  385. The following example arranges a canvas, two scrollbars, and a title
  386. in a frame.
  387. .DS
  388. \f(CWblt_table .frame \\
  389.     .title 0,0 -columnspan 2 -anchor center \\
  390.     .canvas 1,0 -fill both \\
  391.     .vscroll 1,1 -fill y \\
  392.     .hscroll 2,0 -fill x
  393. blt_table column .frame configure 1 -resize none
  394. blt_table row .frame configure 2 -resize none\fR
  395. .DE
  396. .sp 1
  397. The rows and columns containing the scrollbars are frozen at their normal
  398. size, so that even if the frame is resized, the scrollbars will remain
  399. the same width.
  400. .SH BUGS
  401. .VS
  402. There is no warning or error if a window is already a slave or master, 
  403. managed by another geometry manager (there currently is no way to properly 
  404. detect this).  Typically, the window will be repositioned by both geometry 
  405. managers, ad infinitum.  The only recourse is to avoid doing this.
  406. .VE
  407. .SH KEYWORDS
  408. frame, geometry manager, location, table, size
  409.